Code Review

This PR adds two focused documentation improvements for agent readiness: a "When to use Rapidata" section in llms.txt and a step-by-step agent authentication guide in authentication.md and the developer portal. The intent is solid, but there are a few issues worth addressing before merge.

Findings (most severe first)

1. site_root/developers/index.html — Direct token request missing required fields

The inline step 4 describes the non-SDK token request as:

POST https://auth.rapidata.ai/connect/token with grant_type=client_credentials

This omits client_id, client_secret, and scope. The full example in docs/authentication.md (lines 48–52) shows all three are required:

-d scope="openid email roles"

And the Scopes section explicitly states: "Tokens are scoped. The SDK requests openid roles email by default."

A developer following only the developer portal page will construct an incomplete token request and may receive a token with missing scopes, leading to 403 Forbidden on API calls. Even if there's a "Full details" link at the bottom, this step should at minimum mention that scopes are required, or omit the inline example entirely and just link through.

2. site_root/llms.txt lines 31–33 — Bare cross-references are unresolvable

The new paragraph ends with:

"…use the Python SDK (pip install rapidata, see Quick Start) or the OAuth 2.0 REST API (see Authentication). Coding agents can install the official skill (see AI agents)…"

Every other cross-reference in the file uses a full absolute URL (e.g., line 38: [Quick Start](https://docs.rapidata.ai/latest/quickstart/), line 69: [Use Rapidata from your AI agent](https://docs.rapidata.ai/latest/ai_agents/)). Since llms.txt is specifically designed for LLM consumption, bare "see X" references without URLs are dead ends — a model cannot resolve them. The same three targets already have linked entries elsewhere in the file.

Fix: convert to the same Markdown hyperlink format used throughout, or remove the sentence (the content is already covered with proper links in ## API & AI agents).

3. site_root/llms.txt — New section substantially duplicates existing content

The new ## When to use Rapidata section re-covers ground already stated in the file:

• Header (line 3): "Rapidata provides human feedback at scale: crowd-sourced labeling, model evaluation, ranking, and preference data (RLHF-style)" — duplicated by all four bullet points in the new section.
• Line 69: "an official skill that teaches coding agents (Claude Code, Cursor, Copilot, and others) to write Rapidata integrations" — duplicated by the new section's final sentence.
• Line 73: pip install rapidata — already present in the header (line 8) and the Access section.

The CLAUDE.md rule is: "not repeat information." The new section adds length without adding facts not already present (with better links) elsewhere in the file. Consider consolidating: the "not the right tool for" exclusions are genuinely new and useful, but the rest is redundant.

4. docs/authentication.md — Step 1 of new section duplicates the preceding section

The "## Get credentials" section directly above the new block says:

"Create a client ID and secret under Rapidata Settings → Tokens"

Step 1 of the new section says:

"1. Create a client ID and secret at Rapidata Settings → Tokens"

These are near-verbatim. Step 1 should reference the preceding section rather than repeat the instruction, e.g.: "1. Complete the steps in Get credentials above."

Overall the auth step-by-step is a useful addition and the llms.txt "when not to use" guidance is genuinely new. The main thing to fix before merge is the incomplete token request description in the developer portal.